<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <title>User Manual in DocBook/XML</title>
  <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
  <style type="text/css">
  <!--
    body {
      font-family: Verdana,Helvetica,Arial,sans-serif;
      font-size: small;
    }
    code,pre {
      font-family: "Courier New",Courier,monospace;
      font-size: 1em;
    }
    h3 {
      padding: 2px;
      border-left: 4px solid #FFCC00;
      border-bottom: 1px solid #FFCC00;
    }
    h4 {
      padding: 2px;
      border-left: 8px solid #FF9933;
      border-bottom: 1px solid #FF9933;
    }
    pre {
      margin-left: 25px;
      margin-right: 25px;
      padding: 5px;
      background-color: #EEEEEE;
      border-left: 10px solid #CCCCCC;
    }
  -->
  </style>
</head>
<body>
<h2>User Manual in DocBook/XML</h2>
<p>Our Manual is written in DocBook and we generate HTML and CHM manuals for distributing.</p>

<h3>Useful DocBook resources:</h3>
<ul>
  <li><a href="http://www.docbook.org/">Official DocBook homepage</a></li>
  <li><a href="http://www.docbook.org/wiki/moin.cgi/">DocBook Wiki</a></li>
</ul>

<h3>Editing manual</h3>
<p>The user's manual is XML, so you can use XML editor or your favourite text editor. Note that
XML requires document to be well formed, unlike HTML, before it can be processed.
So if possible, make sure your DocBook is well formed before submitting document
patches.</p>

<p>See these tutorials for editing DocBook:</p>
<ul>
  <li><a href="http://newbiedoc.sourceforge.net/metadoc/docbook-guide.html.en">NewbieDoc DocBook guide</a></li>
  <li><a href="http://www.codeproject.com/winhelp/docbook_howto.asp">Creating HTML help from DocBook</a></li>
  <li><a href="http://docbook.sourceforge.net/release/dsssl/current/doc/html/">Customising HTML output with DSSL</a></li>
  <li><a href="http://docbook.sourceforge.net/release/dsssl/current/doc/print/">Customising print formats with DSSL</a></li>
  <li><a href="http://www.sagehill.net/docbookxsl/index.html">DocBook XSL: The Complete Guide</a></li>
</ul>

<p><b>Note:</b> For screenshots we prefer the PNG format. Only for images (for example <em>icons</em>),
where we want transparency, we use the GIF format, since older browsers have problems with transparent PNG images.</p>

<h3>Installing conversion tools needed:</h3>
<ul>
  <li>
    <p>The hard way: <code>libxml</code> and <code>xsltproc</code></p>
    <ul>
      <li>
        <a href="http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/segmentedhtml/">Good instructions</a><br>
        Read ch 3. about how to install Windows environment. Note that only libxml and DocBook DTD are needed for creating HTML documentation.
      </li>
      <li><a href="ftp://ftp.zlatkovic.com/pub/libxml/">libxml download</a></li>
    </ul>
  </li>
  <li>
    <p>Easier with complete command-line environment:</p>
    <ul>
      <li><a href="http://www.e-novative.info/software/ede.php">eDE</a> which is easy to setup environment for DocBook, and its GPL.</li>
    </ul>
  </li>
  <li>
    <p><a href="http://www.cygwin.com/">Cygwin</a> contains needed tools:</p>
    <ul>
      <li><a href="http://ourworld.compuserve.com/homepages/hoenicka_markus/cygbook1.html">Long manual for cygwin and XML</a></li>
      <li><a href="http://www.coin-or.org/Clp/userguide/howto/docbook4clp.html">Shorter and easier manual for cygwin and docbook</a></li>
    </ul>
  </li>
  <li><p><a href="#ownbuildsystem">Our preferred build system</a> based on Java and Saxon.</p></li>
</ul>

<h3><a name="ownbuildsystem">Our preferred build system is based on Java and Saxon</a></h3>
<p>Our preferred build system uses the following tools:</p>
<ul>
  <li><a href="http://www.java.com/getjava/">Java Runtime Environment</a></li>
  <li><a href="http://saxon.sourceforge.net/">Saxon</a></li>
  <li><a href="http://www.docbook.org/xml/">DocBook DTD</a></li>
  <li><a href="http://sourceforge.net/project/showfiles.php?group_id=21935&amp;package_id=16608">XSL StyleSheets</a></li>
  <li><a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp">HTML Help Compiler</a></li>
</ul>
<p>The easiest way is to download <a href="http://sourceforge.net/project/showfiles.php?group_id=13216&amp;package_id=284332&amp;release_id=614099">our manual build tools package v1</a>. The package contains required tools for
manual building. <a href="http://www.java.com/getjava/">Java Runtime (JRE)</a>
is the only external requirement. Installing the tools is easy - just unzip the
tools package to folder <code>/Docs/Users/Manual/build</code>.</p>

<p>The batch files are also located at the same <code>build</code> subfolder.
The main file is <code>build.bat</code>. Paths to the installed tools are written in the <code>configuration.bat</code> file.</p>
<dl>
  <dt><code>build.bat html</code> or <code>build_html.bat</code></dt>
  <dd>Creates the HTML files under the <code>html</code> subdirectory at the <code>build</code> directory.</dd>
  <dt><code>build.bat html withads</code> or <br> <code>build_html.bat withads</code></dt>
  <dd>Creates the HTML files with adds under the <code>html</code> subdirectory at the <code>build</code> directory.</dd>
  <dt><code>build.bat htmlhelp</code> or <br> <code>build_htmlhelp.bat</code></dt>
  <dd>Creates the CHM file under the <code>htmlhelp</code> subdirectory at the <code>build</code> directory.</dd>
  <dt><code>build.bat</code></dt>
  <dd>Is the same like <code>build.bat html</code>.</dd>
</dl>
</body>
</html>